Checking Arguments

IDL allows a user to provide any number of arguments, of any type, to system functions and procedures. IDL checks for a valid number of arguments but the routine itself must check the validity of types. This task consists of examining the argv argument to the routine checking the type and flags field of each argument for suitability. The IDL_StoreScalar() function (see “Storing Scalar Values”) can be very useful in checking write-only arguments.

A number of macros exist in order to simplify testing of variable attributes. All of these macros accept a single argument—the VPTR to the argument in question. The macros check for a desired condition and use the IDL_Message() function with the IDL_MSG_LONGJMP action to return to the interpreter if an argument type doesn’t agree. Some of these macros overlap, and some are contradictory. You should select the smallest set that covers your requirements for each argument. For an example that uses one of these macros, see Example: A Complete Numerical Routine Example (FZ_ROOTS2).

IDL_EXCLUDE_UNDEF

The argument must not be of type IDL_TYP_UNDEF. This condition is usually imposed if the argument is intended to provide some input information to the routine.

IDL_EXCLUDE_CONST

The argument must not be a constant. This condition should be specified if your routine intends to change the value of the argument.

IDL_EXCLUDE_EXPR

The argument must not be a constant or a temporary variable (i.e., the argument must be a named variable). Specify this condition if you intend to return a value in the argument. Returning a value in a temporary variable is pointless because the interpreter will remove it from the stack as soon as the routine completes, causing it to be freed for re-use.

The IDL_VarCopy() and IDL_StoreScalar() functions automatically check their destination and issue an error if it is an expression. Therefore, if you are using one of these functions to write the new value into the argument variable, you do not need to perform this check first.

IDL_EXCLUDE_FILE

The argument cannot be a file variable as returned by the IDL ASSOC function. Most system routines exclude file variables—they are handled by a small set of existing routines. This check is also handled by the IDL_ENSURE_SIMPLE macro, which also excludes structure variables.

IDL_EXCLUDE_STRUCT

The argument cannot be a structure.

IDL_EXCLUDE_COMPLEX

The argument cannot be IDL_TYP_COMPLEX.

IDL_EXCLUDE_STRING

The argument cannot be IDL_TYP_STRING.

IDL_EXCLUDE_SCALAR

The argument cannot be a scalar.

IDL_ENSURE_ARRAY

The argument must be an array.

IDL_ENSURE_OBJREF

The argument must be an object reference heap variable.

IDL_ENSURE_PTR

The argument must be a pointer heap variable.

IDL_ENSURE_SCALAR

The argument must be a scalar.

IDL_ENSURE_STRING

The argument must be IDL_TYP_STRING.

IDL_ENSURE_SIMPLE

The argument cannot be a file variable, a structure variable, a pointer heap variable, or an object reference heap variable.

IDL_ENSURE_STRUCTURE

The argument must be IDL_TYP_STRUCT.